/*
 * Code for blog.techhead.biz
 * Distributed under BSD-style license
 */

package biz.techhead.funcy;

/**
 * FuncE (funky), is the interface after which this library was named.
 * 
 * <p>A FuncE (in combination with a {@link Tuple}) can be used to
 * represent virtually any Java method in a generic way. Therefore, it is useful
 * for implementations of factories, expressions, statements, predicates, etc.
 * See {@link SugarFunc}.
 * 
 * <p>FuncE adds a kind of (albiet verbose) support to Java for closures
 * and first-class functions and methods.
 * 
 * <code><pre>&nbsp;{@literal
 * import static biz.techhead.funcy.Iterables.Set;
 * import static biz.techhead.funcy.Iterables.List;
 * import static biz.techhead.funcy.SugarFunc.Predicate;
 *
 * //Closure example
 *
 * final Set<Integer> luckyNums = Set(2, 5, 7).immutable();
 * FuncyList<Integer> nums = List(9, 2, 5, 8, 3, 6, 2, 9, 7, 4, 5, 6, 8, 4, 9);
 *
 * // Predicate is a "magical" implementation of FuncE.
 * // The subset method actually calls for a FuncE.
 * List<Integer> subset = nums.subset(new Predicate<Integer>()
 *     { void lucky() { out = luckyNums.contains(in); } });
 *
 * assert subset.equals( List(2, 5, 2, 7, 5) );
 * }</pre></code>
 *
 * @param <O> The output type of the function
 * @param <I> The input type of the function
 * @param <E> The exception type of the function
 *            (or see {@link Func} if the function
 *            does not need to throw a checked exception)
 *
 * @see Func
 * @see SugarFunc
 * @see Funcs
 * @see Tuple
 * @see Tuples
 *
 * @author Jonathan Hawkes <jhawkes at techhead.biz>
 */
public interface FuncE<O,I,E extends Throwable> {

    O call(I in) throws E;
}
